<!--
        Copyright (c) 2008 All rights reserved
                Asemantics S.r.l

  Redistribution and use in source and binary forms, with or without
  modification, are permitted provided that the following conditions
  are met:

  1. Redistributions of source code must retain the above copyright
     notice, this list of conditions and the following disclaimer. 

  2. Redistributions in binary form must reproduce the above copyright
     notice, this list of conditions and the following disclaimer in
     the documentation and/or other materials provided with the
     distribution.

  3. The end-user documentation included with the redistribution,
     if any, must include the following acknowledgment:
        "This product includes software developed by 
         Asemantics S.r.l."
     Alternately, this acknowledgment may appear in the software itself,
     if and wherever such third-party acknowledgments normally appear.

  4. All advertising materials mentioning features or use of this software
     must display the following acknowledgement:
     This product includes software developed by Asemantics S.r.l.
     the Semantic Web company, Rome, London, Leiden and its contributors. 

  5. Neither the name of the company nor the names of its contributors
     may be used to endorse or promote products derived from this software
     without specific prior written permission.

  THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  OF THE POSSIBILITY OF SUCH DAMAGE.
-->

<!--
    author: Simone Tripodi (simone.tripodi)
    version: $Id: PROPOSAL.html 197 2009-01-06 10:41:09Z simone.tripodi $
--> <html>
<head>
<title>Proposal Digester-Annotations package for Digester Package</title>
</head>
<body bgcolor="white">

<div align="center">
<h1>Proposal for <em>Digester-Annotations</em> Package</h1>
</div>

<h3>(0) Rationale</h3>

<p>The Apache <a href="http://commons.apache.org/digester/">Digester</a>
is a great, light and fast XML to the Java objects mapping package; it works with
the SAX APIs and is written in Java language and distributed under the
Apache License.
</p>

<p>Inspired by the basic idea behind the JPA's specifications, the
digester-annotations package would add some facilities to configure the
commons-digester using the Java language metadata annotations.</p>

<p>A Commons package would give committers an opportunity to coordinate
their efforts to create and maintain an efficient, feature-rich package
under the ASF license.
</p>

<h3>(1) Scope of the Package</h3>

<p>This is not intended to be a replacement of the commons-digester package,
but rather an extension or an <i>add-on</i>, or also a <i>subproject</i>.</p>

<p>Actually the digester can be configured in various ways:
<ul>
<li>instancing and registering digester's rules into the digester;</li>
<li>using the shorthand registration methods;</li>
<li>using the xmlrules package.</li>
</ul>

Even if these methods are excellent, they are limited - if Java objects are due
to be changed quickly, all previous methods need to be extended/modified -
using the annotated Java object it's possible to create - in runtime or compile-time
- the digester parser, avoiding manual updates. Of course, this approach has
limitations too - i.e. it doesn't work with 3rd part developed objects - but the
combined use of the different approaches should reduce the manually produced
code.</p>

<p>The package should:
<ul>
<li>have a simple to use API;</li>
<li>be compliant with digester rules;</li>
<li>cover as much as possible all the digester features.</li>
</ul>
</p>

<h3>(1.5) Interaction With Other Packages</h3>

<p><em>digester-annotations</em> relies on:
</p>

<ul>
  <li>Java Development Kit (Version 5 or later);</li>
  <li>commons-logging (Version 1.1.1 or later);</li>
  <li>commons-digester (Version 1.8 or later).</li>
</ul>

<h3>(2) Initial Source of the Package</h3>

<p>The initial codebase is an Open-Source project based on Digester
<a href="http://code.google.com/p/digester-annotations">digester-annotation</a>.
</p>

<p>The proposed package name for the new component is
org.apache.commons.digester.annotations.
</p>

<h3>(3) Required Apache-Commons Resources</h3>

<ul>

<li>SVN Repository - New directory <code>digester-annotation</code> in the
<code>apache-commons</code> SVN repository.</li>

<li>Initial Committers - TBD.</li>

<li>Mailing List - Discussions will take place on the general
<em>dev@commons.apache.org</em> mailing list. To help list
subscribers identify messages of interest, it is suggested that the
message subject of this component be prefixed with
[Digester-Annotations].</li>

<li>Jira - New component "Digester-Annotations" under the "Commons" product
category, with appropriate version identifiers as needed.</li>

</ul>


<h3>(4) Initial Committers</h3>

<p>The initial committer on the Digester component shall be:</p>

<ul>
  <li>Simone Tripodi</li>
</ul>

</body>
</html>
